Reading the adherence dashboard

The adherence dashboard is regenerated on every build. This page explains how to read it. It is hand-written; the dashboard itself is generated by the extractor at notes/tools/extract-adherence.mjs.

At a glance

The dashboard opens with a single line: Overall: green or Overall: red. Green means every gated metric is at its target. Red means at least one is off — the same line lists which ones, and the per-metric sections below carry the detail.

Below the badge are five sections, in this order:

1. Test binding
2. Orphan tests
3. Build-gate health
4. Coverage by area
5. Migration progress

A sixth section, Malformed entries, only appears when the extractor finds a stipulation entry that started migrating to the new format but is missing required pointers, or whose pointer paths do not resolve to real files. Malformed entries also fail the script (non-zero exit), which fails the build.

What each metric means

Test binding

Counts how many stipulations have a matching test. Matched means a test in the test index points back at the stipulation by its short slug. Uncovered means the stipulation exists but no test claims it.

• Target: zero uncovered.
• Owner: Jonathan, assisted by the collaborator. When a slice opens, write the missing test alongside.

Orphan tests

Counts test entries whose stipulation pointer references a slug that does not exist in the catalogue.

• Target: zero.
• Owner: Jonathan. Either rename the test's pointer to a real slug, or add the stipulation it pins.

Build-gate health

Records the outcome of the most recent build. Green if the docs build exited cleanly, red if it did not. The wrapper script writes this into a small status file every time yarn adherence finishes a build, and the next run picks it up.

• Target: green.
• Owner: Jonathan. A red gate blocks all merge work until the build is green again.

Coverage by area

For every area listed in areas.json, shows how many stipulations the catalogue holds for it and how many load-bearing modules exist in the area. Coverage is the ratio. An area is green when it has at least one stipulation per module, red when below, and not yet audited when the module count is still zero.

• Target: every opted-in area at one stipulation per module or higher.
• Owner: Jonathan. A red area triggers an extraction sprint — read the load-bearing modules in that area, write the missing invariants, and add them to the catalogue.

Migration progress

A reading dial, not a gate. Shows how many of the legacy stipulations have moved to the new format (id, test pointer, code pointer) and how many are still on the old "Covered:" shape. Migration is a "grow on demand" task — every time a load-bearing module is touched, its stipulations move over.

What each red value triggers

Red value	Action	Owner
Test binding red (uncovered count above zero)	Open a test-writing slice; one test per uncovered stipulation.	Jonathan (collaborator drafts)
Orphan tests red	Catalogue review; either fix the test's pointer or add the missing stipulation.	Jonathan
Build-gate red	Stop new feature work; fix the build first.	Jonathan
Coverage red in an area	Schedule an extraction sprint, time-boxed to a week.	Jonathan
Malformed entries section appears	Fix the broken entry before the next build can pass.	Jonathan

The hand-recorded triggers — re-read recency stale, new-work compliance below target, two or more "unclear, pause" tickets — live in the adherence log, not on the auto dashboard.

When the dashboard is wrong

If the dashboard reports a number that does not match what is in the catalogue, suspect:

1. The extractor missed a code-fenced block (it tries to skip them; if a fence pattern is unusual, an entry inside the fence may have leaked into the parse).
2. A stipulation is migrating but malformed — see the malformed section.
3. A test pointer or code pointer points at a path that no longer exists after a rename.

The fixture-based validator at notes/tools/validate-adherence.mjs re-runs on demand and confirms the parse and cross-join behave as expected. Run it whenever the extractor itself is changed.